package net.wanderinghorse.jsonmessage;

/**
 * The interface used for dispatching the "work" parts of request/response handling
 * after a response is found for a given request.
 *
 * This callback plays two roles:
 *
 * - It is analog to the onResponse() Request callback in the JS API.
 *
 * - It provides the basic interface used for feeding in-bound requests
 * to a handler which can populate a response object based on that request.
 */
public interface RequestHandler {
    /**
     * Must "handle" the given request by populating the given response
     * object. Generally speaking the implementation must read any impl-specific
     * state from req and update resp's state accordingly.
     *
     * Implementations may throw arbitrary exceptions if the incoming
     * request fails to meet the requirements of the implementation (e.g.
     * missing data which cannot be defaulted) or if they encounter a runtime
     * error (e.g. database not available). Alternately, they may report errors
     * by setting the error state of the resp object, e.g. setResultCode()
     * and setResultText().
     *
     * The request object must not be modified by this function.
     *
     * @param req The request object which caused the fetching of the response.
     * @param resp The response object to populate.
     * @throws Exception Implementations may throw arbitrary exceptions.
     */
    void processResponse(Request req, Response resp) throws Exception;
}